AmigActive 21/AACD 21.iso/AACD/Programming/Scalos/Developer/Autodoc/scalos.doc

Text File | 2000-06-01 | 21.1 KB | 861 lines

TABLE OF CONTENTS

scalos.library/--background
scalos.library/SCA_WBStart
scalos.library/SCA_SortNodes
scalos.library/SCA_NewAddAppIcon
scalos.library/SCA_RemoveAppObject
scalos.library/SCA_NewAddAppWindow
scalos.library/SCA_NewAddAppMenuItem
scalos.library/SCA_AllocStdNode
scalos.library/SCA_AllocNode
scalos.library/SCA_FreeNode
scalos.library/SCA_FreeAllNodes
scalos.library/SCA_MoveNode
scalos.library/SCA_SwapNodes
scalos.library/SCA_OpenIconWindow
scalos.library/SCA_LockWindowList
scalos.library/SCA_UnLockWindowList
scalos.library/SCA_AllocMessage
scalos.library/SCA_FreeMessage
scalos.library/SCA_InitDrag
scalos.library/SCA_EndDrag
scalos.library/SCA_AddBob
scalos.library/SCA_DrawDrag
scalos.library/SCA_UpdateIcon
scalos.library/SCA_MakeWBArgs
scalos.library/SCA_FreeWBArgs
scalos.library/SCA_RemapBitmap
scalos.library/SCA_ScreenTitleMsg
scalos.library/SCA_MakeScalosClass
scalos.library/SCA_FreeScalosClass
scalos.library/SCA_NewScalosObject
scalos.library/SCA_DisposeScalosObject



--background
    This library is used as application interface for the Scalos
    workbenchreplacement. It's only available if Scalos is running.
    This means if the library-open fails Scalos isn't running.

    For information about NodeList see SortNodes() and Node see
    AllocStdNode().

    NAME
    SCA_WBStart

    SYNOPSIS
    succ SCA_WBStart (ArgArray, Taglist, NumArgs )
                     A0       A1       D0

    BOOL SCA_WBStart ( APTR ArgArray , APTR Taglist, ULONG NumArgs );

    FUNCTION
    The first argument is used as filename for the to started program.
    The Locks inside the ArgArray are automatically unlocked (use DupLock)
    and the strings are copied.

    INPUTS
    ArgArray - Standard Workbench Args
    NumArgs - Number of Args in the ArgArray. This must be at least
          one.
    Taglist -
        SCA_IconObject - diskobject.library - IconObject to get
                information from it. No icon will be
                loaded.
        SCA_Stacksize - stacksize if no icon is available
        SCA_Flags -
            SCAB_WBStart_NoIcon - don't read an icon.
            SCAB_WBStart_Wait - wait until the program returns
            SCAB_WBStart_PathSearch - search through paths
            SCAB_WBStart_NoIconCheck - don't check icontype

    RESULT

    succ - FALSE if the start fails. It only fails if not enough
           memory available or the WBL task couldn't be started.
           If the program couldn't be loaded it will return TRUE, because
           of it doesn't wait for the returncode of WBL task.

    NOTE
    Locks will not be unlocked if this function fails!

    SEE ALSO
    diskobject.library


    NAME
    SCA_SortNodes

    SYNOPSIS
    SCA_SortNodes (NodeList, CompareFunc, SortType)
                 A0          A1          D0

    void SCA_SortNodes ( struct ScalosNodeList, struct Hook, ULONG SortType);

    FUNCTION
    Sorts a list of MinNodes and uses the CompareFunc to find differences
    between to nodes. NodeList is a pointer to a APTR which points to the
    first node. The first node has as mln_succ a NULL and the last node
    has as mln_pred a NULL. Only mln_succ, mln_pred and the address of the
    of the first will changed. Nothing will be reallocated or freed.

    The CompareFunc will be called with a pointer to one node in A1 (Node0)
    and a pointer to second node in A2 (Node1). You have to return a
    specific value in D0:
          0    if Node0 = Node1
          1    if Node0 < Node1
         ~1    if Node0 > Node1

    INPUTS
    NodeList - Pointer to an APTR which is a pointer to the first node
    CompareFunc - Pointer to a Hook structure for the compare function
    SortType -
        SCA_SortType_Bubble    : enhanced BubbleSort
        SCA_SortType_Selection    : SelectionSort
        SCA_SortType_Insertion    : InsertionSort
        SCA_SortType_Quick    : QuickSort
        SCA_SortType_Best    : The nodes will be counted and then
                      the best SortType will be used.
    RESULT

    SEE ALSO
    SCA_AllocNode, SCA_AllocStdNode, SCA_FreeNode, SCA_FreeAllNodes, SCA_MoveNode, SCA_SwapNodes


    NAME
    SCA_NewAddAppIcon

    SYNOPSIS
    AppObject = SCA_NewAddAppIcon (ID, UserData, IconObject, MessagePort, Taglist)
       D0                      D0     D1         A0          A1          A2

    struct AppObject SCA_NewAddAppIcon( ULONG ID, ULONG UserData, struct IconObject, struct MessagePort, APTR Taglist);

    FUNCTION
    Adds an icon to the mainwindow of the Scalos-screen. See
    workbench.library - AddAppIcon for more information.

    INPUTS
    ID, UserData - will be passed through the AppMessage
    IconObject - diskobject.library - IconObject, IDTM_Layout should not
    to be done.
    MessagePort - a MsgPort where you will receive the AppMessage
    Taglist - no tags at this time.

    RESULT
    AppObject - a private structure to be pass to RemoveAppObject or NULL
                if fails

    SEE ALSO
    SCA_NewAddAppWindow, SCA_NewAddAppMenuItem, SCA_RemoveAppObject


    NAME
    SCA_NewAddAppWindow

    SYNOPSIS
    AppObject = SCA_NewAddAppWindow (ID, UserData, Window, MessagePort, Taglist)
       D0                        D0     D1       A0        A1          A2

    struct AppObject SCA_NewAddAppWindow( ULONG ID, ULONG UserData, struct Window, struct MessagePort, APTR Taglist);

    FUNCTION
    Same as workbench.library - AddAppWindow. See there for further infor-
    mation.

    INPUTS
    ID, UserData - will be passed through the AppMessage
    Window - Intuition Window
    MessagePort - a MsgPort where you will receive the AppMessage
    Taglist - no tags at this time.

    RESULT
    AppObject - a private structure to be pass to RemoveAppObject or NULL
                if fails

    SEE ALSO
    SCA_NewAddAppIcon, SCA_NewAddAppMenuItem, SCA_RemoveAppObject


    NAME
    SCA_NewAddAppMenuItem

    SYNOPSIS
    AppObject = SCA_NewAddAppMenuItem (ID, UserData, Text, MessagePort, Taglist)
       D0                          D0     D1      A0       A1          A2

    struct AppObject SCA_NewAddAppWindow( ULONG ID, ULONG UserData, APTR Text, struct MessagePort, APTR Taglist);

    FUNCTION
    Same as workbench.library - AddAppMenuItem. See there for further infor-
    mation.

    INPUTS
    ID, UserData - will be passed through the AppMessage
    Text - a pointer to the menutext
    MessagePort - a MsgPort where you will receive the AppMessage
    Taglist - no tags at this time.

    RESULT
    AppObject - a private structure to be pass to RemoveAppObject or NULL
                if fails

    SEE ALSO
    SCA_NewAddAppIcon, SCA_NewAddAppWindow, SCA_RemoveAppObject


    NAME
    SCA_RemoveAppObject

    SYNOPSIS
    succ = SCA_RemoveAppObject (AppObject)
     D0                        A0

    BOOL SCA_RemoveAppObject (struct AppObject);

    FUNCTION
    Removes an AppObject from Scalos. This could be an Icon, a Window or
    a MenuItem.

    INPUTS
    AppObject - result from NewAddAppIcon,NewAddAppWindow or NewAddAppMenuItem

    RESULT
    succ - currently it results ever TRUE

    SEE ALSO
    SCA_NewAddAppIcon, SCA_NewAddAppWindow, SCA_NewAddAppMenuItem


    NAME
    SCA_AllocStdNode

    SYNOPSIS
    Node = SCA_AllocStdNode (NodeList, NodeType)
     D0                     A0        D0

    struct MinNode SCA_AllocStdNode (struct ScalosNodeList, ULONG NodeType);

    FUNCTION
    Allocates a standard Scalos-node. It's the only compatible why to
    allocate one of the standard nodes. NEVER allocate a node yourself and
    pass it to Scalos! The scalos.library will use a memorypool for all
    nodes to decrease the memoryfragmentation. The new node will be the
    last in your NodeList and it is cleared public memory. Don't change
    mln_succ and mln_pred yourself, use the node function instead.
    See SCA_SortNodes() for information about the NodeList.

    INPUTS
    NodeList - Pointer to an APTR which is a pointer to the first node
    NodeType - see scalos.(h|i)

    RESULT
    Node - Node at the end or the NodeList

    NOTE
    Node *MUST* be freed with SCA_FreeNode() or SCA_FreeAllNodes()
    This function preserves all registers except D0.

    SEE ALSO
    SCA_AllocNode, SCA_FreeNode, SCA_FreeAllNodes, SCA_MoveNode, SCA_SortNodes, SCA_SwapNodes


    NAME
    SCA_AllocNode

    SYNOPSIS
    Node = SCA_AllocNode (NodeList, Size)
     D0                  A0      D0

    struct MinNode SCA_AllocNode (struct ScalosNodeList, ULONG Size);

    FUNCTION
    Allocates a node and inserts it at the end of the NodeList. Use this
    function only for your own node-handling. Never allocate a standard
    Scalos-node, use SCA_AllocStdNode() instead. Size is the number of bytes
    that allocated after the the MinNode. This means the memsize of node
    is size+MLN_SIZE.
    See SCA_AllocStdNode() for further information.

    INPUTS
    NodeList - Pointer to an APTR which is a pointer to the first node
    Size - bytes after MLN_SIZE

    RESULT
    Node - Node at the end or the NodeList

    NOTE
    Node *MUST* be freed with SCA_FreeNode() or SCA_FreeAllNodes()!
    This function preserves all registers except D0.

    SEE ALSO
    SCA_AllocStdNode, SCA_FreeNode, SCA_FreeAllNodes, SCA_MoveNode, SCA_SortNodes, SCA_SwapNodes


    NAME
    SCA_FreeNode

    SYNOPSIS
    SCA_FreeNode (NodeList, Node)
                 A0      A1

    void SCA_FreeNode (struct ScalosNodeList, struct MinNode);

    FUNCTION
    Removes the Node out of the NodeList and Frees a node allocated with
    SCA_AllocStdNode() or SCA_AllocNode().

    INPUTS
    NodeList - pointer to an APTR which is a pointer to the first node
    Node - node to remove and free

    RESULT

    NOTE
    Node must be part of NodeList!
    This function preserves all registers.

    SEE ALSO
    SCA_AllocStdNode, SCA_AllocNode, SCA_FreeAllNodes, SCA_MoveNode, SCA_SortNodes, SCA_SwapNodes


    NAME
    SCA_FreeAllNodes

    SYNOPSIS
    SCA_FreeAllNodes (NodeList)
                     A0

    void SCA_FreeAllNodes (struct ScalosNodeList);

    FUNCTION
    Will free the whole list of nodes.

    INPUTS
    NodeList - pointer to an APTR which is a pointer to the first node

    RESULT

    NOTE
    This function preserves all registers.

    SEE ALSO
    SCA_AllocStdNode, SCA_AllocNode, SCA_FreeNode, SCA_MoveNode, SCA_SortNodes, SCA_SwapNodes


    NAME
    SCA_MoveNode

    SYNOPSIS
    SCA_MoveNode (SrcNodeList, DestNodeList, Node)
                  A0            A1        D0

    void SCA_MoveNode (struct ScalosNodeList, struct ScalosNodeList, struct MinNode);

    FUNCTION
    Will remove the Node from SrcNodeList and will insert the Node at
    the end of DestNodeList.

    INPUTS
    SrcNodeList - pointer to an APTR which is a pointer to the first node
    DestNodeList - pointer to an APTR which is a pointer to the first node
    Node - MinNode

    RESULT

    NOTE
    This function preserves all registers.

    SEE ALSO
    SCA_AllocStdNode, SCA_AllocNode, SCA_FreeNode, SCA_FreeAllNodes, SCA_SortNodes, SCA_SwapNodes


    NAME
    SCA_SwapNodes

    SYNOPSIS
    SCA_SwapNodes ( SrcNode, DestNode, NodeList)
                  A0        A1        A2

    void SCA_SwapNodes (struct MinNode, struct MinNode, struct ScalosNodeList);

    FUNCTION
    Swaps the positions of SrcNode and DestNode inside the NodeList.

    INPUTS
    SrcNode - MinNode
    DestNode - MinNode
    NodeList - pointer to an APTR which is a pointer to the first node

    RESULT

    NOTE
    SrcNode and DestNode *MUST* be part of NodeList!
    This function preserves all registers.

    SEE ALSO
    SCA_AllocStdNode, SCA_AllocNode, SCA_FreeNode, SCA_FreeAllNodes, SCA_MoveNode, SCA_SortNodes


    NAME
    SCA_OpenIconWindow

    SYNOPSIS
    succ SCA_OpenIconWindow ( TagList )
     D0                     A0

    BOOL SCA_OpenIconWindow ( APTR taglist );

    FUNCTION
    opens a windowtask filled with icons. All information will be given
    as tags:
        SCA_IconNode - fullfilled iconnode
        SCA_IconObject - diskobject.library - iconobject
        SCA_Path - the path to open
        SCA_WindowTitle - windowtitle parsestring ( take a look at the
                  prefsprogram for info)
        SCA_WindowRect - windowsize (see diskobject.library)
        SCA_XOffset,SCA_YOffset - virtual position
        SCA_PatternNumber - backgound pattern number which is con-
                    figured in "Scalos Pattern" prefs
        SCA_ShowAllFiles - TRUE or FALSE
        SCA_ViewModes - viewmodes for the window
            SCAV_ViewModes_Icon
            SCAV_ViewModes_Name
            SCAV_ViewModes_Date
            SCAV_ViewModes_Size
        SCA_Flag -
            none available yet
        SCA_Iconify - TRUE or FALSE for open iconified

    INPUTS
    TagList - taglist

    RESULT
    succ - Success

    NOTE
    One of SCA_IconNode, SCA_IconObject or SCA_Path must be given!

    SEE ALSO


    NAME
    SCA_LockWindowList

    SYNOPSIS
    windowlist SCA_LockWindowList ( accessmode )
     D0                             D0

    struct windowlist SCA_LockWindowList ( LONG accessmode );

    FUNCTION
    Locks the windowlist and returns. This function is a main interface of
    the Scalos-API. The messageport should be used to comunicate with a
    windowtask. No window can be closed while the windowlist is locked.
    For more information take a look at the ScalosAPI documentation.

    INPUTS
    accessmode -
        SCA_LockWindowList_Shared - locks the windowlist for a read-
                                    only access
        SCA_LockWindowList_Exclusiv - read and write access is know
                                      available

    RESULT
    windowlist - a struct windowlist

    NOTE
    Normally you should not use the SCA_LockWindowList_Exclusiv. If you
    lock the windowlist exclusiv you should NEVER use intuition calls!

    SEE ALSO


    NAME
    SCA_UnLockWindowList

    SYNOPSIS
    SCA_UnLockWindowList ()

    void SCA_UnLockWindowList ( void );

    FUNCTION
    Unlocks a with LockWindowList() locked windowlist.

    INPUTS

    RESULT

    SEE ALSO


    NAME
    SCA_AllocMessage

    SYNOPSIS
    message SCA_AllocMessage( messagetype, additional_size)
       D0                      D0            D1

    struct message SCA_AllocMessage ( ULONG messagetype, UWORD additional_size );

    FUNCTION
    Allocates a message which could be sent to Scalos. It's the only
    future-compatible way to do this. The scalos-message signature and the
    the messagetype will be set and the returned memory is cleared.

    INPUTS
    messagetype -
        see ScalosAPI.doc
    additional_size - number of bytes that will be added to the size of
                  the message. Normally this should be NULL.

    RESULT
    message - a full-filled scalos-message of the selected type or NULL

    NOTE
    Never try to free a message yourself, it will cause a memory trashing!
    Scalos uses fast memorypool functions for its messages.

    SEE ALSO


    NAME
    SCA_FreeMessage

    SYNOPSIS
    SCA_FreeMessage( message )
                   A1

    void SCA_FreeMessage ( struct message );

    FUNCTION
    Frees a with SCA_AllocMessage() allocated message.

    INPUTS
    message - struct scalos-message (returned from AllocMessage())

    RESULT

    SEE ALSO


    NAME
    SCA_InitDrag

    SYNOPSIS
    DragHandle SCA_InitDrag( Screen )
        D0                 A0

    struct DragHandle SCA_InitDrag ( struct Screen );

    FUNCTION
    Inits special bobroutines. This routines are easy to use and
    support 24bit bobs.

    INPUTS
    Screen - the screen to use for the bobs or NULL for the default
             Scalos screen

    RESULT
    DragHandle - a private structure to pass it to the other Drag functions

    SEE ALSO


    NAME
    SCA_EndDrag

    SYNOPSIS
    SCA_EndDrag( DragHandle )
                 A0

    void SCA_EndDrag ( struct DragHandle );

    FUNCTION
    Removes all bobs from screen and frees it, if nessesary it unlocks
    the layers.

    INPUTS
    DragHandle - result from SCA_InitDrag()

    RESULT

    SEE ALSO


    NAME
    SCA_AddBob

    SYNOPSIS
    succ SCA_AddBob( DragHandle, Bitmap, Mask, Width, Height, XOffset, YOffset )
     D0              A0        A1     A2     D0     D1       D2       D3

    BOOL SCA_AddBob ( struct DragHandle, struct Bitmap, APTR Mask, ULONG Width, ULONG Height, LONG XOffset, LONG YOffset );

    FUNCTION
    Addes a bitmap to the Boblist. Bitmap and Mask will be copied, it can be
    freed after calling this function. Mask is a planar bitplane the width
    divided by 8 and height. It must be in Chipram. X and Y offsets are the
    offset from movepoint give in SCA_DrawDrag(). Normaly it's the relativ position
    to the mouse pointer.

    INPUTS
    DragHandle - result from InitDrag()
    Bitmap - a standard bitmap structure, any depth allowed
    Mask - width/8 * height mask for the bitmap
    Width - width in pixels
    Height - height in pixels
    XOffset - relative x-position to the movepoint
    YOffset - relative y-position to the movepoint

    RESULT
    succ - TRUE if anything went well, FALSE if some problem occured

    SEE ALSO


    NAME
    SCA_DrawDrag

    SYNOPSIS
    SCA_DrawDrag( DragHandle, X, Y, Flags )
                 A0      D0 D1   D2

    void SCA_DrawDrag ( struct DragHandle, LONG X, LONG Y, ULONG Flags );

    FUNCTION
    Blits the bobs to the selected screen relative to the given position.

    INPUTS
    DragHandle - result from SCA_InitDrag()
    X - movepoint x direction
    Y - movepoint y direction
    Flags -
        SCAF_Drag_Transparent - draw all bobs transparent, normaly it's a
                                raster

    RESULT

    SEE ALSO


    NAME
    SCA_UpdateIcon

    SYNOPSIS
    SCA_UpdateIcon( WindowType, UpdateIcon, UpdateIcon_Size )
                    D0          A0             D1

    void SCA_UpdateIcon ( UBYTE WindowType, struct UpdateIcon, ULONG ui_SIZE );

    FUNCTION
    Refreshes an icon specified in UpdateIcon structure. The icon will be loaded,
    removed or reloaded. The UpdateIcon struct depents on the windowtype.

    INPUTS
    WindowType - windowtype which should be updated
    UpdateIcon - special information, depents on WindowType
    UpdateIcon_Size - size of the UpdateIcon structure in bytes

    RESULT

    SEE ALSO


    NAME
    SCA_MakeWBArgs

    SYNOPSIS
    number = SCA_MakeWBArgs( Buffer, Iconnode, ArgsSize )
                           A0       A1        D0

    ULONG SCA_MakeWBArgs ( APTR Buffer, struct Iconnode, ULONG ArgsSize);

    FUNCTION
    Generates a WBArgs Array from all selected icons except the given Iconnode.

    INPUTS
    Buffer - Memory to save the Lock and Name pointers
    Iconnode - an iconnode to exclude or NULL
    ArgsSize - Size*8 of the buffer

    RESULT
    number - number of args generated

    SEE ALSO


    NAME
    SCA_FreeWBArgs

    SYNOPSIS
    number = SCA_FreeWBArgs( Buffer, Number, Flags )
                           A0      D0     D1

    void SCA_FreeWBArgs ( APTR Buffer, ULONG Number, ULONG Flags);

    FUNCTION
    Frees a ArgArray generated with MakeWBArgs.

    INPUTS
    Buffer - Array with WBArgs structures
    Number - Number of WBArgs to free
    Flags -
        SCAB_FreeLocks - free the Locks
        SCAB_FreeName - free the namefields

    RESULT

    SEE ALSO


    NAME
    SCA_RemapBitmap

    SYNOPSIS
    SCA_RemapBitmap( SrcBitmap, DestBitmap, PenArray )
                      A0        A1         A2

    void SCA_RemapBitmap ( struct Bitmap, struct Bitmap, APTR PenArray);

    FUNCTION
    Exchanges the pens in a bitmap. PenArray includes the information about
    which pen in SrcBitmap should be which one in DestBitmap.
    The bitmaps have to be standard bitmaps, no displayable or interleaved
    flags are supported. Never remap a bitmap allocated with of friend
    bitmap.

    INPUTS
    ScrBitmap - source Bitmap
    DestBitmap - destination Bitmap or NULL if the SrcBitmap should be
             replaced
    PenArray - array of bytes with pennumbers

    RESULT

    SEE ALSO


    NAME
    SCA_ScreenTitleMsg

    SYNOPSIS
    SCA_ScreenTitleMsg( Format, Args )
                      A0     A1

    void SCA_ScreenTitleMsg ( APTR Format, APTR Args);

    FUNCTION
    Show a message on ScreenTitle of all Scalos windows.

    INPUTS
    Format - FormatString or NULL to recover the standard title. All RawDoFmt()
                 args are allowed
    Args - the arguments for the formatstring

    RESULT

    SEE ALSO
    exec.library/RawDoFmt


    NAME
    SCA_MakeScalosClass

    SYNOPSIS
    SCA_MakeScalosClass ( ClassName, SuperClassName, InstSize, DispFunc )
         D0           A0            A1          D0        A2

    struct ScalosClass SCA_MakeScalosClass ( APTR ClassName, APTR SuperClassName, UWORD InstSize, APTR DispFunc);

    FUNCTION
    Addes a new BOOPSI Class to the internal classlist. ClassName may be a new
    name or a classname that's already available. In this case the class will
    replace or enhance a known class.

    INPUTS
    ClassName - name of the new class or NULL for a private class
    SuperClassName - name of the super class for the new class
    InstSize - size of the instance variables
    DispFunc - pointer to your Dispatcher function

    RESULT
    ScalosClass - a ScalosClass structure or NULL if it fails

    NOTE
    If you like a add a subclass to your private class then use the intuition
    class functions.

    SEE ALSO
    intuition.library/MakeClass


    NAME
    SCA_FreeScalosClass

    SYNOPSIS
    scc SCA_FreeScalosClass( ScalosClass )
    D0                       A0

    BOOL SCA_FreeScalosClass ( struct ScalosClass );

    FUNCTION
    Removes a ScalosClass from the internal classlist.

    INPUTS
    ScalosClass - return value from SCA_MakeScalosClass()

    RESULT
    succ - FALSE if the class couldn't be removed, else TRUE

    SEE ALSO
    SCA_MakeScalosClass, intuition.library/FreeClass


    NAME
    SCA_NewScalosObject

    SYNOPSIS
    Object SCA_NewScalosObject( ClassName, TagList )
      D0                        A0       A1

    struct Object SCA_NewScalosObject ( APTR ClassName, APTR TagList);

    FUNCTION
    Allocates and inits a new BOOPSI Object.

    INPUTS
    ClassName - Scalos Classname
    TagList - taglist (depents on the class)

    RESULT
    Object - BOOPSI Object or NULL

    SEE ALSO
    intuition.library/NewObject


    NAME
    SCA_DisposeScalosObject

    SYNOPSIS
    SCA_DisposeScalosObject( Object )
                           A0

    void SCA_DisposeScalosObject ( struct Object );

    FUNCTION
    Disposes a object created with NewScalosObject.

    INPUTS
    Object - BOOPSI Object

    RESULT

    SEE ALSO
    intuition.library/DisposeObject